<!DOCTYPE html>
<html>
<head>
<title>XSCHEM TUTORIAL: Use symgen.awk to create symbols from 'djboxsym' compatible text files</title>
<link rel="stylesheet" type="text/css" href="xschem_man.css" />
<style type="text/css">
/* Local styling goes here */
p{padding: 15px  30px 10px;}
</style>

</head>
<body>

<!-- start of slide -->
<div class="content">   
<!-- navigation buttons -->
<a href="xschem_man.html" class="home">UP</a>

 <!-- slide title -->
 <h1>TUTORIAL: Use symgen.awk to create symbols from 'djboxsym' compatible text files</h1>
 <p>
  The <kbd>symgen.awk</kbd> utility (installed in <kbd>(install_root)/share/xschem</kbd>) generates xschem 
  symbol files from a textual description that is backward compatible to DJ Delorie's perl 
  <a href="http://www.gedasymbols.org/user/dj_delorie/tools/djboxsym.html">djboxsym</a> symbol
  generator for the geda schematic editor (gschem, lepton-schematic).
  
  A sample <kbd>sample.symdef</kbd> file is the following:
 </p>
 <pre class=code style="height: 240px;">

# This is a sample symbol definition for documenting djboxsym.  Some
# of the pins have been intentionally mistyped in order to demonstrate
# all combinations of flags.  DO NOT USE AS A CP2201 REFERENCE!

[labels]

SAMPLE
refdes=U?
DEMO ONLY
! copryright=2006 DJ Delorie
! author=DJ Delorie
! uselicense=unlimited
! distlicense=GPL
! device=sample device
! description=ethernet controller
! footprint=QFN-28

[left]
24 ! CS
.bus
11  AD0
12  AD1
13  AD2
14  AD3
15  AD4
16  AD4
17  AD6
18  AD7

21 &gt; ALE
22 ! RD/(DS)
23 !&gt; WR/(R/!W)

25 ! INT
29  \_RESET\_

[right]
10 ! RST
26 &gt; MOTEN
1 !&gt; LA

6 TX+
7 TX-

5 RX+
4 RX-

28 XTAL1
27 XTAL2
[top]
3 AV+
8 VDD1
30 !&gt; \_CLK\_
19 VDD2

[bottom]
2 AGND
9 DGND1
20 DGND2
 </pre>
 <p>
  Creating the symbol is simple: <br>
   <kbd>&lt;install_path&gt;/share/xschem/symgen.awk sample.symdef &gt; sample.sym</kbd><br>
  The resulting symbol is shown here under, side-compared with the same symbol generated by djboxsym for gschem:
 </p>
 <img src = "symgen_vs_djboxsym.png" style="max-width: 100%;">
 <p>
  Another <kbd>sample2.symdef</kbd> file specifically created to generate a perfectly valid xschem symbol (including
  attributes for spice netlisting) is the following: 
 </p>
 <pre class=code style="height: 240px;">
#  &lt;pinnumber&gt;  &lt;direction&gt;[&lt;circle&gt;&lt;edge_trigger&gt;] &lt;name&gt;
# circle: !
# edge_trigger: &gt;
# direction is mandatory: i=input, o=output, b=bidirectional (inout)

[labels] 
FAKE IC TO TEST XSCHEM SYMGEN
STEFAN FREDERIK SCHIPPERS
@symname
@name
! type=subcircuit
! format="@name @pinlist @symname"
! template="name=x1"
--vmode
[left]
24   i!   CHIP_SELECT
.bus
11   i    AD0
12   i    AD1
13   i    AD2
14   i    AD3
15   i    AD4
16   i    AD5
17   i    AD6
18   i    AD7

21   i&gt;   ALE

22   i!   \_RD\_
23   i!&gt;  \_WR\_
25   i!   INTERRUPT_REQUEST
[right]
10   i!   RST
26   i&gt;   MOTEN
1    i!&gt;  LA
6    o    TXP
7    o    TXM

5    i    RXP
4    i    RXM
28   i    XTAL1
27   i    XTAL2
[top]
3    io    AVP
.bus
29  o!    DATA0
30  o!    DATA1
31  o!    DATA2
32  o     DATA3
33  o     DATA4
34  o!    DATA5
35  o!    DATA6
36  o!    DATA7
37  o!    DATA8
38  o     DATA9
39  o&gt;    DATA10
40  o&gt;    DATA11
41  o&gt;    DATA12
42  o     DATA13
43  o     DATA14
44  o     DATA15

8    io    VDD1
19   io    VDD2
45   io    VDD_ANALOG
46   io    VDD_DIGITAL
[bottom]
2    io!   GND_ANALOG
47   io!   GND_DIGITAL
9    io&gt;   DGND1
20   io&gt;   GND2
 </pre>
 <img src = "tutorial_symgen_02.png" style="max-width: 100%;">
 <p>
  some extensions of xschem's symdef text file format with respect to original 
  <a href="http://www.gedasymbols.org/user/dj_delorie/tools/djboxsym.html">djboxsym</a> format:
  <ul>
  <li>
   In addition to optional <kbd>!</kbd> (inversion bubble) and <kbd>&gt;</kbd> (edge trigger) specifiers
   XSCHEM's <kbd>symgen.awk</kbd> accepts a pin direction specifier, 
   <kbd>i</kbd>, <kbd>o</kbd>, <kbd>io</kbd> and <kbd>p</kbd> (latter one for power pins, treated by xschem as inout)
   for 'input', 'output', 'inout' (bidirectional) direction and 'power'. These attributes are fundamental
   for digital simulations (Verilog, Vhdl). If this specifier is missing (as it is in djboxsym 
   .symdef files) then the direction is assumed as <kbd>b</kbd> (inout).
   XSCHEM does not have any specific direction for power pins so they are treated as 'inout' <br>
   <i>Port direction specifiers are indeed supported also by 'djboxsym' but not documented.</i>
  </li>
  <li>
   Option <kbd>--vmode</kbd> given <b>before</b> any pin declaration like in djboxsym sets vertical orientation for top / bottom pins.
  </li>
  <li>
   <kbd>.bus</kbd> specifier can be used for all pin orientations, left, top, right, bottom if <kbd>--vmode</kbd>
   is enabled, otherwise it will affect only spacing of left/right pins.
  </li>
  <li> 
   Option <kbd>--auto_pinnumber</kbd> given <b>before</b> any pin declaration lets <kbd>symgen.awk</kbd>
   automatically add pin numbers, so the first field may be omitted
  </li>
  <li>
   Edge trigger (>) and inversion bubble (!) specifiers are drawn on all sides, not only left/right.
  </li>
  <li> 
   Option <kbd>--hide_pinnumber</kbd> given <b>before</b> any pin declaration avoids
   pin numbers in generated symbol. If this option is used 
   it is mostly done together with <kbd>--auto_pinnumber</kbd> to get rid of pin numbers completely.
  </li>
  </ul>
 </p>

 <!-- end of slide -->
 <div class="filler"></div>
</div>

<!-- frame footer -->
<iframe seamless src="xschem_footer.html"  class="footer_iframe" >
</body>
</html>

